fix: recover preview dependency history across cold renderers - #4459

sequenceDiagram
  participant Browser
  participant ModuleServer
  participant PackageRegistry
  participant HistoryReader
  participant HistoryAPI
  Browser->>ModuleServer: Request pinned module key
  ModuleServer->>PackageRegistry: Resolve requested dependency snapshot
  PackageRegistry->>HistoryReader: Read metadata history with signal
  HistoryReader->>HistoryAPI: Fetch project and branch history
  HistoryAPI-->>HistoryReader: Return validated history
  HistoryReader-->>PackageRegistry: Select matching historical snapshot
  PackageRegistry-->>ModuleServer: Return snapshot-bound module graph
  ModuleServer-->>Browser: Serve pinned module

• Fix all pre-merge checks with AI

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

📦 Client bundle boundary

A server module in a client graph aborts hydration in the browser. New leaks fail CI; known leaks are tracked in scripts/lint/client-bundle-baseline.json to burn down.

Codecov Report

❌ Patch coverage is 92.94991% with 38 lines in your changes missing coverage. Please review.

📢 Thoughts on this report? Let us know!

Codex independent review

Reviewed exact SHA 547797568f74e321ed48a3f784793eabad82e4c5 against base 9c3c32c570d37417adc2348eceba91e08d4e01d4 and issue veryfront/veryfront-issue-inbox#1042.

No actionable findings in this framework diff.

The implementation matches the scoped recovery contract: metadata is bounded and validated without invoking accessors or proxy traps; project and branch scope must match; only the exact requested dependency key is reconstructed; the API-provided expiry is retained; recovered history never becomes current writeback authority; release and unbound sources do not consult mutable history; and an explicit shared snapshot store never falls back to this reader. The framework's companion contract with veryfront/veryfront-api#4729 agrees on the v1 envelope, project/branch identity, 16-entry limit, millisecond expiry, and project-scoped bearer authorization.

The effect-bearing tests reside in the semantic integration boundary. Coverage shard 1 runs them serially with integration permissions, converts the supplemental raw profiles with the repository's existing source/test filters, and merges that LCOV into the existing shard artifact without changing artifact count or the 80% threshold. The final change from 1a076c5 to 5477975 only narrows the static parameter type of the descriptor reader from object to Record<string, unknown> | readonly unknown[]; all callers already pass one of those validated shapes, so runtime output and failure behavior are unchanged.

Verification:

• Pinned base-to-head implementation reviewed; final one-line delta confirmed as 1 insertion/1 deletion and git diff --check passed
• Pinned Deno 2.7.7 changed-file type checks passed
• Metadata validation/reconstruction suite: 18 steps passed
• Package registry history/authority/branch suite: 10 steps passed
• API client, filesystem adapter, wrapper, and workflow contract suites: 110 steps passed
• Independent warm/cold/replacement process regression plus generated inline and external Chromium hydration: 3 steps passed, one document request and no browser errors
• Semantic integration placement, anti-slop policy, supplemental coverage flow, repository lint stages, and full pre-push checks passed for the final source

Verification and rollout gaps: direct Node/Bun spot checks could not start in this isolated worktree because the generated npm/node_modules artifact was absent. Exact-head CI attempt 1 encountered two artifact-service 403 failures during coverage upload and Node artifact download after source tests passed; failed jobs are being retried unchanged as attempt 2, so this review does not represent CI as green. Strict staging platform-ui/ai-live remains rollout evidence after the API-first deployment. The companion API's atomic history-budget repair must land, pass its own review and CI, and deploy first. This framework approval does not attest or bypass those gates.

Verdict: APPROVE

Score: 98/100

Review-Gate:
Reviewer: Codex
Reviewed-SHA: 5477975
Score: 98/100
Actionable-Findings: 0
Verdict: APPROVE

@codex review

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

gitar display:verbose         

_{Was this helpful? React with 👍 / 👎 | Gitar}

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 8660818cb6

Updated to 1a076c530fc97855928f7206e2db2747536ca5ce.

• Provisioned Chromium through the existing shared installer for the integration browser regression.
• Proved request-branch history scope and kept cross-scope recovery fail-closed; resolved the original review thread.
• Fixed standalone test typechecks and moved the three effect-bearing tests into the repository's semantic integration location.
• Preserved their coverage in the existing shard-1 artifact using the existing LCOV merge helper; thresholds and consumers remain unchanged.
• Removed all four Sonar findings. The preceding production-code-identical head passed Sonar with zero new issues and 89.6% new-code coverage; final-head CI is running.

Final local full pre-push checks passed. API-first rollout and fresh strict staging health remain required.

@codex review

Updated to 5477975: narrowed the descriptor helper input to its actual record/array types, satisfying the repository type-policy audit. All CI lint stages were verified locally; the final registry smoke stage passed after correcting the local Deno executable path. Full pre-push checks passed. @codex review

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 547797568f

CI passed on the final reviewed head after artifact-service retries. Marking this PR ready so review reconciliation can finish while the API staging release runs. Merge remains held until API #4729 is verified on all staging API replicas; auto-merge is disabled.

@codex review

@codex review

Codex independent review

Reviewed exact SHA 7ac829350d2191aa856fe74c55921a6e2752fbd2 against base 9c3c32c570d37417adc2348eceba91e08d4e01d4, issue veryfront/veryfront-issue-inbox#1042, the PR discussion, and the authenticated history boundary.

Finding

[HIGH] Authenticated dependency history still crosses mutable runtime hooks.

Files: src/platform/adapters/veryfront-api-client/operations.ts:386-402, src/platform/adapters/veryfront-api-transport.ts:547-563

The new returnText path protects JSON.parse, Array.prototype.map, and the final output copy, but the authenticated response bytes first pass through ambient typed-array and decoder methods in readSuccessfulResponseText(). The parsed entry also passes through the generic Zod array/object copier before the descriptor-safe copy. Project code running in the shared renderer can therefore install hooks that observe another request history response.

I reproduced both paths on this exact head:

• replacing %TypedArray%.prototype.set observed a private dependency marker while the API read still succeeded;
• installing an inherited Array.prototype["0"] setter observed the authenticated history entry during Zod array parsing while the API read still succeeded.

This leaves the P1 cross-project metadata exposure open. Validate and copy this endpoint through a fully captured boundary: captured typed-array allocation/copy/subarray and TextDecoder construction/decode, followed by descriptor/index-based validation that does not route authenticated values through the generic Zod object/array copier. Add regressions for typed-array set, inherited numeric array/object setters, and decoder/subarray replacement after module initialization.

The remaining recovery logic matches the scoped contract: exact canonical key only, project/branch identity checks, original expiry, rollback reads, no current-write authority, and no metadata fallback when an explicit shared store exists.

Verification:

• Pinned Deno 2.7.7 deno check passed for all 26 modified TypeScript files.
• Focused API history suite passed 14 steps.
• git diff --check passed.
• Two independent runtime-hook probes reproduced the exposure on the exact reviewed SHA.
• I did not duplicate the full pre-push suite or wait on CI; the release gate owner retains those checks.

Verdict: REQUEST CHANGES

Score: 68/100

Review-Gate:
Reviewer: Codex
Reviewed-SHA: 7ac8293
Score: 68/100
Actionable-Findings: 1
Verdict: REQUEST CHANGES

@codex review

Codex final review of 4a2013ccbacc00edf22afb3477489a69410be915 against base 9c3c32c570d37417adc2348eceba91e08d4e01d4.

Findings: No actionable correctness, regression, security, bounds, or rollout issues found.

The implementation matches #1042's bounded recovery increment:

• src/transforms/esm/dependency-metadata-history.ts:83-145 validates the complete project/branch envelope before selection, rejects expired or over-retained history, enforces the aggregate byte ceiling before hashing, and reconstructs only the exact requested canonical key.
• src/transforms/esm/package-registry.ts:595-655 keeps remembered/shared/current lookup ahead of history, excludes release and unbound sources, preserves captured configuration across flag/cohort rollback, and never makes recovered history current writeback authority.
• src/transforms/esm/dependency-snapshot-registry.ts:164-208 disables the metadata path when an explicit shared store exists, keeps original expiry, checks exact key/canonical bytes, and caches only after validation.
• src/platform/adapters/veryfront-api-client/operations.ts:449-480 binds reads to the expected project and canonical branch, uses a 1 MiB bounded/cancellable response read, and suppresses authenticated error bodies. Adapter initialization and body cancellation propagate through the filesystem layers.
• src/modules/server/module-server.ts:350-358 continues serving canonical pinned paths after rollout rollback without relaxing malformed/duplicate/unknown key rejection.

Validation performed (pinned Deno 2.7.7):

• deno task test:file across 9 changed unit/integration regression files: 14 test groups, 335 steps passed, including warm/cold/replacement processes and inline/external Chromium hydration.
• deno check --no-lock passed for the changed history, registry, adapter, API client, and transport entry points.
• deno fmt --check passed for all 31 changed TS/Markdown/workflow files.
• git diff --check passed; targeted scan found no secrets, empty catches, debug logging, silent compatibility bypasses, or broad best-effort fallback added to production code.

Gaps: I did not rerun the full unit suite or strict remote staging health in this independent pass. Direct checking of the module-server entry point still reaches unchanged repository React default-export declaration diagnostics; the PR's affected history/transport entry points check cleanly. CI was intentionally not awaited for review.

Score: 98/100
Correctness 40/40; tests 20/20; reliability/security 15/15; standards 14/15; scope/rollout 9/10.

Review-Gate:
Reviewer: Codex
Reviewed-SHA: 4a2013c
Score: 98/100
Actionable-Findings: 0
Verdict: APPROVE

Reviewed the CodeRabbit docstring-coverage warning on 4a2013ccbacc00edf22afb3477489a69410be915. It is an informational coverage heuristic over touched functions, not an unresolved correctness finding. The new filesystem capability and its contract are documented in the adapter types and architecture guide; the repository’s public-export JSDoc and documentation checks pass in deno task lint:ci. Private parser helpers and test callbacks keep descriptive names rather than repetitive docstrings. No review thread or public API documentation gap remains from this warning.

@codex review

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: b15a0050fb

Independent final Codex review of b15a0050fb92b20d5d2bd036be0302b90ae351c9 against base 9c3c32c570d37417adc2348eceba91e08d4e01d4.

No actionable findings.

Score breakdown:

• Correctness and completeness: 40/40
• Regression tests and verification: 18/20
• Reliability and security: 15/15
• Repository standards and maintainability: 15/15
• Scope, documentation, and rollout clarity: 10/10

Evidence reviewed:

• The exact-key recovery path accepts only project/branch-matched metadata, reapplies the captured renderer configuration before hashing, retains the API-provided expiry, and keeps recovered history outside current writeback authority. Explicit shared snapshot storage never downgrades to metadata recovery.
• History admission is bounded at 1 MiB per response, 32 retained sources, 8 MiB retained bytes, 64 pending operations, a one-second settled-history TTL, and the registry deadline. Revision changes, expiry, and clear invalidate retained history; rollback reads still detect package changes without re-enabling publication.
• Authenticated response handling uses bounded strict UTF-8 reads, captured parsing/byte intrinsics, descriptor-based field reads, frozen records, null-prototype dependency maps, branch/project identity checks, and suppressed error-body diagnostics. Cancellation reaches adapter initialization waits, fetch retries, and stalled body reads.
• Canonical pinned module paths remain recognized after flag rollback, including fail-closed 409/no-store handling for malformed pins. Release/environment sources and unbound sources do not query mutable history.
• CI wiring installs Chromium for the integration regression and merges the three semantic integration suites into the coverage artifact. The architecture and support docs describe expiry, cache limits, authority separation, rollout behavior, and unsupported direct/expired history.

Verification:

• Pinned Deno 2.7.7 deno task test:file across all nine changed/regression test files: 12 suites, 252 steps, 0 failures.
• Pinned Deno 2.7.7 deno check --no-lock across all 18 modified TypeScript source files: passed.
• Unchanged src/proxy/websocket-client.test.ts, which is the only current failed CI coverage-shard test: 2 suites, 15 steps, 0 failures locally; the file has no pinned diff.
• git diff --check: passed. Exact-head metadata and all 11 review threads were fetched completely; 0 unresolved.

Current gap: exact-head CI is still running, and coverage shard 2/4 has an apparently unrelated failure in the unchanged WebSocket suite. This approval is for the reviewed source; the repository merge gate should still require the final CI disposition. Strict staging verification remains a post-merge rollout requirement, as documented in the PR.

Review-Gate:
Reviewer: Codex
Reviewed-SHA: b15a005
Score: 98/100
Actionable-Findings: 0
Verdict: APPROVE

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
90.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Exact head b15a0050fb92b20d5d2bd036be0302b90ae351c9 has cleared the final review gate: 45 passing checks, 13 documented event-dependent skips, zero pending/failing checks, all 11 review threads resolved, and independent Codex98/100 with zero findings. Coverage attempt2 passed after an unchanged native WebSocket teardown flake; 6,400 local cleanup cycles also passed.

The original queue prefix included #4461, whose automatic shared-cache activation conflicts with the existing provider gate and suppresses this PR’s metadata recovery. The independent blocker is recorded here. Both queued entries were held before changing composition. This reviewed head will now re-enter the normal queue independently, with all required checks preserved. No branch rebase or code change was made.

Staging rollout and strict remote health remain pending merge and release; no production promotion is requested.